home *** CD-ROM | disk | FTP | other *** search
/ Experimental BBS Explossion 3 / Experimental BBS Explossion III.iso / pascal / pkpas1.zip / MANUAL.DOC < prev    next >
Text File  |  1993-10-17  |  11KB  |  247 lines
  1. Reference manual for PKWAREU  version 1.0a     October 1993
  2.  
  3.         This manual contains information on all Procedures, functions and
  4.         declarations available for use, and discriptions on how to use
  5.         them.
  6.  
  7. =====================  Functions and Procedures =============================
  8.  
  9. ------------------------------------------------------------------------------
  10.  GetZipStats
  11. ------------------------------------------------------------------------------
  12.  
  13.         Syntax:
  14.  
  15.                 FUNCTION GetZipStats:WORD;
  16.  
  17.         Returns:
  18.  
  19.           0 - if Signature found and successfully read into "zipstats".
  20.  
  21.           1 - if Signature found does not match, the file is either not a
  22.               zip file or has been damaged.
  23.  
  24.           2 - I do a block read to get the signature, returns 2 if it fails.
  25.  
  26.           Other - higher then 2 are the IOResult errors, as defined
  27.                   in your Turbo Pascal Reference.
  28.  
  29.         Description:
  30.  
  31.         Called after the "Zipfile" has been opened and assigned.
  32.         This procedure, finds the CentralFileHeaderSignature, and reads the
  33.         end of the central directory record into the global variable
  34.         "ZipStats". It also sets the CentralAddress variable to the
  35.         start of the central directory upon success.
  36.  
  37.         NOTE Call this before the other routines, I do not
  38.              check to see if has been called successfully.
  39.  
  40.         Programming notes:
  41.  
  42.                 Needs 50 bytes free on the heap before calling.  This is
  43.                 always restored, and it ain't asking for much.
  44.  
  45. -----------------------------------------------------------------------------
  46.  ReadFileHeader
  47. -----------------------------------------------------------------------------
  48.  
  49.         Syntax:
  50.  
  51.                 FUNCTION ReadFileHeader(VAR CFH: CentralFileHeaderType): Byte;
  52.  
  53.         Returns:
  54.  
  55.           0 - the read was successful contents of CFH should be Okay to use.
  56.         
  57.           1 - Signature is bad do not use CHF, may have read past the last entry.
  58.  
  59.           2 - disk read error, same as GetZipStats error 2 above.
  60.  
  61.           Other - codes are IOResult codes as described above.
  62.  
  63.         Description:
  64.  
  65.         Called after a successful call to GetZipStats above.  Loads the
  66.         CFH with the next Centralfileheader discovered.  The read is
  67.         sequential.  That is the directory is read from start to end, in
  68.         the order they appear.  (This does not always correspond to the
  69.         order the files are actually stored in the zip file, however)
  70.         The Offset of the next header is kept in a four byte variable
  71.         internally, calculated at the time of the last read.  This will
  72.         allow you to close the Zipfile and reopen it at anytime, but in
  73.         stating that... do not alter the ZipStats fields at anytime.
  74.  
  75.         Programming notes:
  76.  
  77.         Minimum heap use will be 46 bytes which is restored on exit of
  78.         the call. NOTE: that only the filename field is of type string,
  79.         FileComment is a character array.  This is done because the length
  80.         discripter for each is a word type not a byte type.  Meaning the
  81.         length of these fields is not limited to Pascal String lengths of
  82.         255.  I have "capped" it to 255, set by the Const PKMaxLen.  This
  83.         means if these fields are longer then PKMaxLen they will have to
  84.         be read by a different method unless you have the source code to
  85.         change PKMaxLen.  This senario also applies to the filename field,
  86.         but should not be of concern for MS-DOS systems where the maximum
  87.         path length is less than 255 characters, or at least I think it is.
  88.  
  89. ------------------------------------------------------------------------------
  90.  CFH_to_FileStat
  91. ------------------------------------------------------------------------------
  92.  
  93.         Syntax:
  94.  
  95.         PROCEDURE CFH_to_FileStat(VAR CFH: CentralFileHeaderType;
  96.                                                           VAR FS: FileStats);
  97.  
  98.         Description:
  99.  
  100.         Converts a CentralFileHeaderType to a FileStats type.  Included
  101.         because you will most likely write a similar routine to manage
  102.         the contents. CFH's are rather large to keep many in memory at one
  103.         time, so I suggest using this as it contians information of interest.
  104.  
  105. ------------------------------------------------------------------------------
  106.  ShowZipComment
  107. ------------------------------------------------------------------------------
  108.  
  109.         Synatx:
  110.  
  111.                 PROCEDURE ShowZipComment;
  112.  
  113.         Description:
  114.  
  115.         Writes the Zip comment to the screen.  NOTE if you have the freeware
  116.         version only the first 15 charaters will write to screen.  PKWARE
  117.         suggests a maximun size of a commment should be 64K.
  118.  
  119. ------------------------------------------------------------------------------
  120.  GetZipComment
  121. ------------------------------------------------------------------------------
  122.  
  123.         Syntax:
  124.  
  125.         Procedure GetZipComment(VAR CPtr: CommentPtr; VAR Size:Word);
  126.  
  127.         Description:
  128.  
  129.         Returns a CommentPtr, as declered in types section, to a character
  130.         array, of length SIZE.  You are responsible to free the heap
  131.         allocated to the pointer.  Range checking must be off for this to
  132.         work.  NOTE if you have the freeware version maximun size returned
  133.         is 15.  PKWARE suggests a maximum size of a comment should be
  134.         64k, so WORD type is used for SIZE.  Does not check if enough free
  135.         heap exists.
  136.  
  137.         See PKdemo1 for details on correct use!
  138.  
  139.  
  140. ======================== Symbols, Types and Constants =========================
  141.  
  142. CONST
  143.  
  144.         CentralFileHeaderSignature    = $02014b50; { As defined by PKWARE }
  145.         CentralFileHeaderEndSignature = $06054b50;
  146.  
  147.         PKMaxLen = 255;        { Max length of Filecomment and ExtraField }
  148.         CommentLen = 15;       { Set to 15 for freeware version           }
  149.  
  150. TYPES
  151.  
  152.         FString = String;
  153.  
  154.         CharArray = Array[1.. PKMaxLen] of CHAR;
  155.  
  156.         CommentPtr = ^CommentPtr;
  157.         CommentArray = Array[1..1] of Char;
  158.  
  159. => FileStats = Record         { just to make storage size managable }
  160.      Name   : String[65];     { includes path                       }
  161.      OSize,                   { original size                       }
  162.      CSize,                   { compressed size                     }
  163.      Date,                    { date and time as longint            }
  164.      CRC    : Longint;        { CRC-32                              }
  165.      Attr   : LongInt;        { actually word TYPE in DOS           }
  166.      Method : Word;           { compression method used             }
  167.    end;
  168.  
  169. => ExtraData = Record
  170.      ExtraName   : String[11];  { name of the data         }
  171.      ExtraID     : Word;        { Id number of the data    }
  172.      ExtraLen    : Word;        { length of the data       }
  173.      ExtraAddress: Longint;     { File offest of the data  }
  174.     end;
  175.  
  176. NOTE: ExtraName is based on the value of ExtraID, first 31 mappings
  177.       are reserved by PKWARE, the rest can be used by a thrid parties.
  178.  
  179.       I set ExtraName to one of :
  180.  
  181.                 $0007 = "AV Info"
  182.                 $0009 = "OS/2"
  183.                 $000C = "VAX/VMS"
  184.                 other = "Proprietary"    { third party assigned }
  185.  
  186. => CentralFileHeaderType = Record     { a.k.a. CFH                      }
  187.       CentralSig   :LongInt;          { Central dir signature           }
  188.       Madeby       : Word;            { HI = Operating system,
  189.                                         Lo = Pkzip version              }
  190.       VerReq       : Word;            { min PK version to extract       }
  191.       GenPurp      : Word;            { Gen. purpose flag               }
  192.       Compresion   : Word;            { Compersion method used          }
  193.       lastFTime    : Word;            { Time of compression             }
  194.       lastFdate    : Word;            { Date of compression             }
  195.       crc32        : LongInt;         { Magic number CRC32              }
  196.       Compsize     : LongInt;         { Compresed file size             }
  197.       UnCompSize   : LongInt;         { Original file size              }
  198.       NameLen      : Word;            { Length of the name              }
  199.       Extralen     : Word;            { Length of extra field           }
  200.       ComentLen    : Word;            { Length of comment               }
  201.       DiskStart    : Word;            { # of disk which this file starts }
  202.       IntrenalAttr : Word;            { LO set indicates ASCII text, 
  203.                                         else is a binary file           }
  204.       ExternalAttr : LongInt;         { HI is operating sys dependant, 
  205.                                         LO is MS-DOS file attr          }
  206.       OffsetLocal  : LongInt;         { Offset from first disk of 
  207.                                         local header                    }
  208.       FileName     : FString;         { Storage for filename,           }
  209.       ExtraName    : ExtraData;       { Storage for extra field         }
  210.       FileComment  : CharArray;       { Storage for File comments       }
  211.      End;
  212.  
  213. NOTE: The CentralFileHeaderType is all the information about a stored file
  214.       available.  Their should be one for each file stored.
  215.  
  216. =>  ZipEndRec = Record
  217.        EndSig      : LongInt;        { Signature of Directroy End                }
  218.        DiskNum     : Word;           { Number of this disk                       }
  219.        DiskwStart  : Word;           { # of disk with start of central dir       }
  220.        NumEntries  : Word;           { # of entries in central dir.
  221.                                          on this disk }
  222.        TNumEntries : Word;           { total number of entries in this
  223.                                        central dir. }
  224.        SizeCentral : LongInt;        { Size of central directory            }
  225.        OffsetDirRelDiskNum: LongInt; { Offest of central dir in respect to
  226.                                        starting disk number                  }
  227.        CommentLen  :Word;            { zipfile comment length                }
  228.       end;
  229.  
  230. NOTE: The ZipEndRec is between the last CFH and the zip file comment,
  231.       only one in any zip file.
  232.  
  233. VAR's
  234.  
  235.    ZipStats       : ZipEndRec;     { Global zipstats }
  236.  
  237. NOTE: This record is used internally, so do not change the fields once set
  238.       by calling GetZipStats.
  239.  
  240.    ZipFile        :File;           { Zip filename.
  241.                                      NOTE: You open and assign and close it ! }
  242.  
  243.    CentralAddress : LongInt;       { Offset of Central directory in file }
  244.                                    { Never change this! }
  245.  
  246. { End manual.doc }
  247.